Title Banner

Previous Book Contents Book Index Next

Inside Macintosh: QuickDraw GX Printing /
Chapter 3 - Page Formatting and Dialog Box Customization / About Page Formatting and Dialog Box Customization

About Collection Objects

QuickDraw GX supports collection objects to store and to allow your application to store printing-related, formatting, and paper-type information associated with a printable document. Essentially, these collections specify additional information that are not absolutely required to print a job, format a document, or specify the kind of paper. In QuickDraw GX printing, collection objects typically store information you can use to customize dialog boxes. You can access information required by your application from these collection objects, however, whether or not you allow the user a choice in a dialog box. You can also use collection objects to store information that is of use only to your application.

You can use collection objects without customizing dialog boxes. For example, a user may print by dragging the document's icon onto a desktop printer or by choosing the Print One Copy menu item from the File menu. In these cases, your application may need to change the settings in a collection object directly, without user intervention.

You can also store information that is not already provided by QuickDraw GX. For example, as part of using QuickDraw GX page formatting features, your application is responsible for managing the correspondence between format objects and individual pages in a document. Your application can use a format collection item to store this correspondence. Storing correspondence information in a format collection is discussed in "Associating Format Objects With Document Pages," which begins on page 3-61.

Collection Tag IDs and Item IDs

When you add data (referred to as a collection item) to a collection object, the Collection Manager associates the data with a collection tag ID and a collection item tag. Together, the 4-byte collection tag ID and the 4-byte collection item tag ID uniquely identify a collection item within a particular collection object.

Note
To avoid the confusion between tag objects (which are not related to collection objects at all), collection tags, and collection item tags, this book refers to collection tags as tag IDs and to collection item tags as item IDs. Tags, when used in this book, refer to tag objects.
QuickDraw GX assigns the gxPrintingTagID tag ID to each of its predefined collection items:

enum { gxPrintingTagID = -28672 };
For each of its collection items, QuickDraw GX defines an item ID, such as gxCopiesTag for the collection item that defines the number of copies to print:

enum {gxCopiesTag = 'copy'};
QuickDraw GX reserves all tag IDs that are negative or less than 127. It also reserves all collection items defined by lowercase characters. For example, you can use your application's registered creator type for the tag ID.

In addition to the collection tag and collection item ID, the Collection Manager allows items to be accessed by index. You can use an index to provide faster access to specific items in a collection or to perform operations on all collection items in a collection object. This index does not uniquely identify an item, however, because adding or removing items can change an item's index number. For information about collection indexes and collection objects in general, see the Collection Manager chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.

Item Structures

A structure defines the form of most collection items. A type definition is associated with each of these structures: 

struct gxCopiesInfo{
   long copies;
};

typedef struct gxCopiesInfo gxCopiesInfo;
For example, you can use gxCopiesInfo as both a structure name and a data type definition:

gxCopiesInfo myCopies;
struct gxCopiesInfo myCopies;
In this book, only the structure definition is presented. Type definitions are only presented when they are not associated with a structure, as in gxCollectionCategory, defined in the next section.

Categories of Collection Items

If you add an item to a collection, you need to decide whether the contents will be valid if the output printer or formatting printer changes. You also must decide if the item should persist when the collection is flattened.

QuickDraw GX purges the items that are not valid after the printer driver changes, based on the contents of the collection item's user attribute bits. It also decides which items to flatten based on these bits. For general information about user attribute bits, see the Collection Manager chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.

A printer-driver switch occurs whenever a user changes the device class (type of printer) of the output printer or formatting printer associated with a particular document. For example, if the user switches output printers, QuickDraw GX discards the tray-feed information, which specifies the current paper tray, because it may have changed.

QuickDraw GX assigns collection object items into categories based on the contents of the gxCollectionCategory user attribute bits, as shown in the following enumeration:

typedef short gxCollectionCategory;

enum {
   gxNoCollectionCategory        = (gxCollectionCategory) 0x0000,
   gxOutputDriverCategory        = (gxCollectionCategory) 0x0001,
   gxFormattingDriverCategory    = (gxCollectionCategory) 0x0002,
   gxDriverVolatileCategory      = (gxCollectionCategory) 0x0004,
   
   gxVolatileOutputDriverCategory = 
            gxOutputDriverCategory + gxDriverVolatileCategory,
   gxVolatileFormattingDriverCategory =
            gxFormattingDriverCategory + gxDriverVolatileCategory
};
Items in the gxNoCollectionCategory category are not purged. Data that is specific to an output printer driver should be grouped in the gxVolatileOutputDriverCategory collection item category. Data that is specific to a formatting printer driver should be grouped in the gxVolatileFormattingDriverCategory collection item category.

Data that need not be saved when a job is flattened should be grouped in the gxDriverVolatileCategory collection item category. You must also clear the collectionPersistenceBit attribute bit if you would like to keep the information but do not require it to be saved with the collection.

The Job Collection

QuickDraw GX primarily stores in a job collection the information contained in the Print dialog box and its General panel, Paper Match panel, and Print Time panel. Panels for the Print dialog box are discussed in the chapter "Introduction to Printing With QuickDraw GX" in this book. QuickDraw GX stores 18 items in a job collection, as shown in Figure 3-1.

Figure 3-1 The job collection

A brief description of each collection item follows. To see how the pieces of data are structured in the collection item, see "Constants and Data Types for Job Collection Items" beginning on page 3-78. Job collection items include the following:

The Format Collection

QuickDraw GX primarily stores information from the Page Setup and Custom Page Setup dialog boxes in a format collection. You need to call the GXChangedFormat function each time you change the format collection.

QuickDraw GX stores nine items in a format collection, as shown in Figure 3-2.

Figure 3-2 The format collection

A brief description of each collection item follows. To see how the pieces of data are structured in the collection item, see "Constants and Data Types for Format Collection Items" beginning on page 3-89. Format collection items include the following:

Note
The page-inversion information, page-flip information (horizontal and vertical), and precise-bitmap information are used, by default, only by PostScript printer drivers.

The Paper-Type Collection

The paper-type collection contains additional information about the paper-type object. QuickDraw GX stores in a paper-type collection five collection items, as shown in
Figure 3-3.

Figure 3-3 The paper-type collection

A brief description of each collection item follows. To see how the pieces of data are structured in the collection item, see "Constants and Data Types for Paper-Type Collection Items" beginning on page 3-94. Paper-type collection items include the following:

Previous Book Contents Book Index Next

© Apple Computer, Inc.
7 JUL 1996




Navigation graphic, see text links

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help